<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2016. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="Content-Type">
  <meta content="text/css" http-equiv="Content-Style-Type">
  <link type="text/css" charset="ISO-8859-1" href="../book.css"
 rel="STYLESHEET">
  <title>Synchronization Support - Beyond the basics</title>
  <link href="../book.css" type="text/css" rel="stylesheet">
</head>
<body style="background-color: rgb(255, 255, 255);">
<h2>Beyond the Basics</h2>
<p>If you plan on providing synchronization support and don't have an existing 
  mechanism for managing synchronization state, this section explains how to implementing 
  a Subscriber from scratch. This means that there is no existing synchronization 
  infrastructure and illustrates how to use some API that is provided to maintain 
  the synchronization state.<br>
</p>
<p>For the remainder of this example we will make use of a running
example. The source code can be found in the file system provider
package of the <a
 href="http://git.eclipse.org/c/www.eclipse.org/eclipse.git/tree/platform-ui/plugins/org.eclipse.ui.examples.filesystem/">org.eclipse.ui.examples.filesystem</a>
plug-in. You should check the project out from the Git repository and
use as a reference while you are reading this tutorial. </p>
<h3>Implementing a Subscriber From Scratch</h3>
<p>This first example assumes that there is no existing infrastructure for maintaining 
  the synchronization state of the local workspace. When implementing a subscriber 
  from scratch, you can make use of some additional API provided in the <em>org.eclipse.team.core</em> 
  plug-in. The <a
 href="../reference/api/org/eclipse/team/core/variants/package-summary.html">org.eclipse.team.core.variants</a> 
  package contains two subclasses of <a
 href="../reference/api/org/eclipse/team/core/subscribers/Subscriber.html">Subscriber 
  </a>which can be used to simplify implementation. The first is <a
 href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.html">ResourceVariantTreeSubscriber 
  </a>which will be discussed in the second example below. The second is a subclass 
  of the first: <a
 href="../reference/api/org/eclipse/team/core/variants/ThreeWaySubscriber.html">ThreeWaySubscriber</a>. 
  This subscriber implementation provides several helpful classes for managing 
  the synchronization state of a local workspace. If you do not have any existing 
  infrastructure, this is a good place to start. </p>
<p>Implementing a subscriber from scratch will be illustrated using the file system 
  example available in the <a
 href="http://git.eclipse.org/c/www.eclipse.org/eclipse.git/tree/platform-ui/plugins/org.eclipse.ui.examples.filesystem/">org.eclipse.ui.examples.filesystem</a> 
  plug-in. The code in the following description is kept to a minimum since it 
  is available from the Eclipse Git repository. Although not technically a three-way 
  subscriber, the file system example can still make good use of this infrastructure. 
  The FTP and WebDAV plug-ins also are built using this infrastructure.</p>
<h3>ThreeWaySubscriber</h3>
<p>For the file system example, we already had an implementation of a <a href="../reference/api/org/eclipse/team/core/RepositoryProvider.html">RepositoryProvider 
  </a>that associated a local project with a file system location where the local 
  contents were mirrored. FileSystemSubscriber was created as a subclass of <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySubscriber.html">ThreeWaySubscriber</a> 
  in order to make use of a <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a> 
  to manage workspace synchronization state. Subclasses of this class must do 
  the following:</p>
<ul>
  <li>create a <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a> 
    instance to manage the local workspace synchronization state.</li>
  <li>create an instance of a <a href="../reference/api/org/eclipse/team/core/variants/ThreeWayRemoteTree.html">ThreeWayRemoteTree</a> 
    subclass to provide remote tree refresh. 
  <ul>
    <li>The class FileSystemRemoteTree was defined for this
purpose</li>
  </ul></li>
  <li>implement a method to create the resource variant handles used to
calculate the synchronization state.
    <ul>
      <li>The class FileSystemResourceVariant (a subclass of <a href="../reference/api/org/eclipse/team/core/variants/CachedResourceVariant.html">CachedResourceVariant</a>) 
        was defined for this</li>
    </ul>
  </li>
  <li>implement the roots method
    <ul>
      <li>The roots for the subscriber are all the projects mapped to
the FileSystemProvider. Callbacks were added to FileSystemProvider
in order to allow the FileSystemSubscriber to generate change
events when projects are mapped and unmapped.</li>
    </ul>
  </li>
</ul>
<p>In addition to the subscriber implementation, the get and put
operations for the file system provider were modified to update the
synchronization state in the ThreeWaySynchronizer. The
operations are implemented in the class
org.eclipse.team.examples.filesystem.FileSystemOperations.</p>
<h3>ThreeWaySynchronizer</h3>
<p><a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a> 
  manages the synchronization state between the local workspace and a remote location. 
  It caches and persists the local, base and remote timestamps in order to support 
  the efficient calculation of the synchronization state of a resource. It also 
  fires change notifications to any registered listeners. The <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySubscriber.html">ThreeWaySubscriber</a> 
  translates these change events into the proper format to be sent to listeners 
  registered with the subscriber.</p>
<p>The <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a> 
  makes use of Core scheduling rules and locks to ensure thread safety and provide 
  change notification batching.</p>
<h3>ThreeWayRemoteTree</h3>
<p>A <a href="../reference/api/org/eclipse/team/core/variants/ThreeWayRemoteTree.html">ThreeWayRemoteTree</a> 
  is a subclass of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTree.html">ResourceVariantTree</a> 
  that is tailored to the <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySubscriber.html">ThreeWaySubscriber</a>. 
  It must be overridden by clients to provide the mechanism for fetching the remote 
  state from the server. <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTree.html">ResourceVariantTree</a> 
  is discussed in more detail in the next example.</p>
<h3>CachedResourceVariant</h3>
<p>A <a href="../reference/api/org/eclipse/team/core/variants/CachedResourceVariant.html">CachedResourceVariant</a> 
  is a partial implementation of IResourceVariant that caches any fetched contents 
  for a period of time (currently 1 hour). This is helpful since the contents 
  may be accessed several times in a short period of time (for example, to determine 
  the synchronization state and display the contents in a compare editor). Subclasses 
  must still provide the unique content identifier along with the byte array that 
  can be persisted in order to recreate the resource variant handle.</p>
<h3>Building on Top of Existing Workspace Synchronization</h3>
<p>Many repository providers may already have a mechanism for managing their synchronization 
  state (e.g. if they have existing plug-ins). The <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.html">ResourceVariantTreeSubscriber</a> 
  and its related classes provide the ability to build on top of an existing synchronization 
  infrastructure. For example, this is the superclass of all of the Git subscribers.</p>
<h4>ResourceVariantTreeSubscriber</h4>
<p>As was mentioned in the previous example, the <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySubscriber.html">ThreeWaySubscriber</a> 
  is a subclass of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.html">ResourceVariantTreeSubscriber</a> 
  that provides local workspace synchronization using a <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a>. 
  Subclasses of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.html">ResourceVariantTreeSubscriber</a> 
  must provide:</p>
<ul>
  <li>
    <p>Subclasses of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTree.html">ResourceVariantTree</a> 
      (or <a href="../reference/api/org/eclipse/team/core/variants/AbstractResourceVariantTree.html">AbstractResourceVariantTree</a>) 
      that provide the behavior for traversing and refreshing the remote resource 
      variants and, for subscribers that support three-way comparisons, the base 
      resource variants.</p>
  </li>
  <li>An implementation of <a href="../reference/api/org/eclipse/team/core/variants/IResourceVariantComparator.html">IResourceVariantComparator</a> 
    that performs the two-way or three-way comparison for a local resource and 
    its base and remote resource variants.It is common to also provide a subclass 
    of <a href="../reference/api/org/eclipse/team/core/synchronize/SyncInfo.html">SyncInfo</a> 
    in order to customize the synchronization state determination algorithm. </li>
  <li>An implementation of the roots method for providing the roots of the subscriber 
    and an implementation of the isSupervised method for determining what resources 
    are supervised by the subscriber.</li>
</ul>
<p>The other capabilities of the subscriber are implemented using these
facilities.</p>
<h4>ResourceVariantTree</h4>
<p><a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantTree.html">ResourceVariantTree</a> 
  is a concrete implementation of <a href="../reference/api/org/eclipse/team/core/variants/IResourceVariantTree.html">IResourceVariantTree</a> 
  that provides the following:</p>
<ul>
  <li>traversal of the resource variant tree</li>
  <li>logic to merge the previous resource variant tree state with the
current fetched state.</li>
  <li>caching of the resource variant tree using a <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantByteStore.html">ResourceVariantByteStore</a>.</li>
</ul>
<p>The following must be implemented by subclasses:</p>
<ul>
  <li>creation of resource variant handles from the cached bytes that
represent a resource variant</li>
  <li>fetching of the current remote state from the server</li>
  <li>creation of the byte store instance used to cache the bytes that
uniquely identify a resource variant</li>
</ul>
<p>Concrete implementations of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantByteStore.html">ResourceVariantByteStore</a> 
  are provided that persist bytes across workbench invocations (<a href="../reference/api/org/eclipse/team/core/variants/PersistantResourceVariantByteStore.html">PersistantResourceVariantByteStore</a>) 
  or cached the bytes only for the current session (<a href="../reference/api/org/eclipse/team/core/variants/SessionResourceVariantByteStore.html">SessionResourceVariantByteStore</a>). 
  However, building a subscriber on top of an existing workspace synchronization 
  infrastructure will typically require the implementation of <a href="../reference/api/org/eclipse/team/core/variants/ResourceVariantByteStore.html">ResourceVariantByteStore</a> 
  subclasses that interface with the underlying synchronizer. For example the 
  <a href="../reference/api/org/eclipse/team/core/variants/ThreeWayRemoteTree.html">ThreeWayRemoteTree</a> 
  makes use of a byte store implementation that stores the remote bytes in the 
  <a href="../reference/api/org/eclipse/team/core/variants/ThreeWaySynchronizer.html">ThreeWaySynchronizer</a>.</p>
<p>The creation of resource variant handles for this example does not differ from 
  the previous example except that the handles are requested from a resource variant 
  tree instance instead of the subscriber.</p>

</body>
</html>
